Skip to main content

Downloading the Talon Community User File Set

After installing Talon and a speech recognition engine, as described here you will need to download a user file set. This wiki is all about the Talon community user file set and so this page is about downloading that specific user file set.

This can be done using two different methods, using zip and using git.

The background to this choice is that if you use Talon for any period of time, you can expect the following:

  • The community will update the user file set with bug fixes and new features, and you will want to update your local copy of it.
  • You might make your own changes to some of these files.

Considerations​

About zip​

This is easier to get started with Talon as it involves only downloading a single file and using standard methods on your PC to extract all the files from it.

The disadvantage is longer term. Periodically on those occasions when you download the latest community user file set, you will manually need to keep track of which files you have changed and make sure those changes aren't lost during the update.

tip

Make a backup of the whole Talon user directory prior to replacing it with a fresh download of the community user file set.

About git​

The benefit of git, is that it makes it easy to obtain the latest files without losing any changes you've made in the meantime. This is a benefit when using Talon longer term.

If you haven't already heard of git, you might find that this approach makes it a little harder to get started with Talon. git is a very extensive tool, but you will only need to use it in a minimal way. Even still, there will be terms that you will come across such as repository, branch and working directory.

git is available as both a command line utility and as a GUI application. If you are not particularly comfortable usihellong a command terminal, you may prefer a GUI application such as GitHub Desktop.

Summary​

If you are not particularly comfortable using a command terminal, and if you are just wanting to explore the suitability of Talon you may wish to use the simpler method of downloading zip files.

You will always be able to switch to using git down the track.

Instructions​

Installing Using the Zip File​

In this method, the zip file is downloaded from: https://github.com/talonhub/community

Click on the Code button:

screenshot of the Talon hub community page on GitHub

And download the zip file:

screenshot of the GitHub code panel
  • Extract the files. If you don’t know how to extract zip files, a quick google search for "extract zip files" may be helpful.
  • Place these extracted files inside the user folder of the Talon Home directory. You can find this folder by right-clicking the Talon icon in the taskbar (Windows) or clicking the Talon icon in the menu bar (Mac), clicking Scripting > Open ~/talon, and navigating to user.

Installing Using Git​

If you wish to install community by using git, proceed as follows:

Linux & Mac​

  1. Install git
  2. Open a terminal (Mac / Ubuntu)
  3. Paste the following into the terminal window then press Enter/Return:
cd ~/.talon/user
git clone https://github.com/talonhub/community community

Windows​

  1. Install git
  2. Open a command prompt
  3. Paste the following into the command prompt window then press Enter:
cd %AppData%\Talon\user
git clone https://github.com/talonhub/community community

Managing Custom Changes and Contributing to the Main Repository Using Git​

If you continue to use Talon for an extended period, you will most likely want to make changes to your configuration. In order to facilitate the integration of changes in the community repository with your own changes, it is strongly recommended to use Git for managing your changes. However, doing so requires more knowledge about Git than can be reasonably explained in a short guide like this. The Pro Git book is an excellent resource to learn about intermediate and advanced Git usage.

Putting Custom Changes Onto Is Their Own Branch​

To manage your custom changes while keeping up with upstream updates, it is advisable to create a personal branch for your modifications:

  1. After cloning the repository, create and switch to a new branch (e.g. git checkout -b custom).
  2. If you make changes, commit them to this branch. Try to avoid creating commits that bunch together unrelated changes.
  3. In regular intervals, fetch changes from the upstream repository and merge the main branch into your custom branch. This may result in merge conflicts that then need to be resolved.
  4. If you do not mind other people looking at your local changes, create a fork of the community repository on GitHub, add it as a second remote to your local working copy, and push your custom branch there.

Using Git Worktrees and Cherry-Picking to Contribute to the Upstream Repository​

If you have made changes to your setup that could improve the experience for a wide range of users, you may want to share these changes with the wider community. If you have followed the recipe in the preceding section, Git makes it easy to create pull requests for your changes. One solution that is used by several regular contributors to community relies on Git worktrees and cherry-picking:

  1. Create a worktree for the upstream repository: git worktree add <some folder outside the talon user directory>/talonhub-community origin/main.
  2. In the worktree, create a new branch for your PR: git checkout -b feature-branch.
  3. Cherry-pick your desired commits from your custom branch: git cherry-pick <commit-hash>.
  4. Push the branch to your fork on GitHub and create a pull request to the upstream repository.

The reason why this setup works so well is that the worktree set up above and the primary worktree in the Talon user directory are part of the same local repository and share all of the references.